Navigating the Notebook - Instructor Script

To familiarise participants with the notebook environment, build up a simple notebook from scratch demonstrating the following operations:

  • Insert & delete cells
  • Change cell type (& know different cell types)
  • Run a single cell from taskbar & keyboard shortcut (shift + Enter)
  • Run multiples cells, all cells
  • Re-order cells
  • Split & merge cells
  • Stop a cell

Let's get started...

Create a new notebook...

The notebook is built up from separate editable areas, or cells.

A new notebook contains a single code cell.

Add a line of code and execute it by:

  • clicking the run button, or
  • click in the cell, and press shift-return

In [3]:
print('hello world')


hello world

To select a cell, click on it. The selected cell will be surrounded by a box with the left hand side highlighted.

Move the selection focus to the cell above/below using the keyboard up/down arrow keys.

Additionally select adjacent cells using SHIFT-UP ARROW or SHIFT-DOWN ARROW.

Managing Cells - Add, Delete, Reorder

Add a new cell to the notebook by:

  • click the + button on the toolbar
  • Insert -> Insert Cell Above or ESC-A
  • Insert -> Insert Cell Below or ESC-B

Delete a cell by selecting it and:

  • click the scissors button on the toolbar
  • Edit -> Delete cells or ESC-X

Undelete the last deleted cell:

  • Edit -> Undo Delete cells or ESC-Z

Each cell has a cell history associated with it. Use CMD-Z to step back through previous cell contents.

Reorder cells by:

  • moving them up and down the notebook using the up and down arrows on the toolbar
  • Edit -> Move Cell Up or Edit -> Move Cell Down
  • cutting and pasting them:
    • Edit - >Cut or Edit->Paste Cells Above or Edit->Paste Cells Below
    • on the toolbar, Cut selected cells then Paste selected cells

You can also copy selected cells from the toolbar, Edit -> Copy Cells or ESC-C.

Managing Cells - Merging and Splitting

If a cell is overlong, you can split it at the cursor point: Edit -> Split Cell

You can merge two cells that are next two each other. Select one cell and then Edit -> Merge Cell Above or Edit -> Merge Cell Below.

The cell type (markdown, code, etc) of the merged cell will be the same as the originally selected cell.

Cell outputs

If the last line of code produces an output, the output will be embedded in the notebook below the code cell:


In [4]:
a=1
b=2

a+b


Out[4]:
3

We Can Run a Cell to Multiple Times

Each time the cell us run, the state of the underlying python process is updated, even if the visual display of other cells in the notebook is not.


In [5]:
print(a)


1

In [6]:
#Run this cell multiple times
a=a+1
a


Out[6]:
2

Code Libraries can be imported via a Code Cell


In [7]:
import numpy as np

np.pi


Out[7]:
3.141592653589793

Clearing Cell Outputs

Clear the output of a selected cell: Cell -> Current Output -> Clear

Clear the output of all cells in the notebook: Cell -> All Output -> Clear

Note the the state of the underlying kernel will not be affected - only the rendered display in the notebook.

Expanding the narrative - Markdown Cells

As well as code cells, we can have cells that contain narrative text.

Change the cell type using the drop down list in the toolbar, or by using the ESC-M keyboard shortcut.

To "open" or select a markdown cell for editing, double click the cell.

View the rendered markdown by running the cell:

  • hit the play button on the toolbar
  • use the SHIFT-RETURN keyboard shortcut.

Markdown cells can contain formatted headings

Prefix a line of text in a markdown cell by one or more # signs, followed by a space, to specify the level of the heading required.

# Heading 1
## Heading 2
...
###### Heading 6

Markdown cells can contain formatted text inline

Prefix a heading with one or more # signs, followed by a space.

Emphasise a word or phrase by wrapping it (no spaces!) with a single * on either side.

Strongly emphasise a word or phrase by wrapping it (no spaces!) with two underscores, __, either side.

Markdown cells can contain lists

Create an unnumbered list by prefixing each list item with a -, followed by a space, with each list item on a separate line:

  • list item 1
  • list item 2

Create a number list by prefixing each list item with a number, followed by a ., followed by a space, with each list item on a separate line:

  1. numbered item 1
  2. numbered item 2

Add sublists by indenting sublisted items with a space:

  • list item
    • sublist item

Add a link using the following pattern: [link text](URL_or_relative_path)

For example, [Data Carpentry](https://datacarpentry.org) gives the clickable link: Data Carpentry.

Add an image using the following pattern: [image alt text](URL_or_path)

For example, [Jupyter logo](./jupyter-logo.png) embeds the following image:

Markdown cells can contain inline styled (non-executable) code

Style inline code by including the code in backticks: `code style` gives code style inline.

Create a block of code by wrapping it at the start and end with four backticks:

def mycode():
    ''' Here is my non-executable code '''
    pass

Markdown cells can include Latex Expressions

Mathematical expessions can be rendered inline by wrapping a LaTeX expression (no spaces) with a $ either side.

For example, $e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i$ is rendered as the inline $e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i$ expression.

Wrapping the expression with $$ either side forces it to be rendered on a new line in the centre of the cell: $$e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i$$

Working Code Cells Harder

As well as running code in the kernel, code cells can be used in a couple of other ways.

As a command prompt:

  • as a route to the command line on the desktop of the machine the Jupyter server is running on:
    • start the code cell with a ! and then enter you command line command.
    • eg Mac/Linux: !pwd
    • eg WIndows: !cd

Cell magic:

IPython has a notion of cell magics, commands prefixed by a % or %% that run a particular command or wrap content of the cell in some way before executing it.

  • %matplotlib inline: enable the inline display of matplotlib generated graphics
  • %whos: display a list of variables and their values as set in the kernel
  • %env: display a list of environment variables and their current values in the host environment.

Code cells can produce rich output too

Cell outputs can include tables and images


In [19]:
import pandas as pd

pd.DataFrame({'col1':[1,2],'col2':['x','y']})


Out[19]:
col1 col2
0 1 x
1 2 y

In [8]:
%matplotlib inline

import matplotlib.pyplot as plt

# Create 1000 evenly-spaced values from 0 to 2 pi
x = np.linspace(0, 2*np.pi, 1000)  

#Plot a sine wave over those values
y = np.sin(x)

plt.plot(x, y)

#You can prevent the display of object details returned from the plot by:
## - adding a semi-colon (;) at the end of the final statement


Out[8]:
[<matplotlib.lines.Line2D at 0x109b64f98>]

Notebooks Can be Support Interactive Widgets that Help You Explore a Dataset

If you reate a function that accepts one or more parameters, you may be able to use it as the basis of an automatically generated application.

For example, suppose we have a function that will plot a sine wave over the range 0..2 pi for a specified frequency, passed into the function as a parameter:


In [20]:
#If no frequency value is specified, use the default setting: f=1

def sinplot(f=1):
    #Define a range of x values
    x = np.linspace(0, 2*np.pi, 1000)  

    #Plot a sine wave with the specified frequency over that range
    y = np.sin(f*x)

    #Plot the chart
    plt.plot(x, y)
    
sinplot(f=3)


Using ipywidgets interact()

Pass the name of your function, and the default values of the parameters, to the ipywidgets interact() function to automatically create interactive widgets to control the parameter values.


In [10]:
from ipywidgets import interact

interact(sinplot, f=5)


Out[10]:
<function __main__.sinplot>

Specify the Range of Values Applied to an interact() slider

Passing in a single number associated with a numerical parameter sets the default (mid-point) of a slider range. Passing in two values sets the range.

The defualt value will be the default value set in the function definition.


In [11]:
interact(sinplot, f=[0,20])


Out[11]:
<function __main__.sinplot>

Specify the Step Size of a Slider

Passing three values in as a list for a numerical parameter, and they define the minumim, maximum and step size values for the slider.


In [12]:
interact(sinplot, f=[0,20,5])


Out[12]:
<function __main__.sinplot>

HTML code an also be included in a markdown cell. Adding an empty anchor tag allows you to create named anchor links that can act as deeplinks into particular parts of the notebook:

<a name='navigation'></a>

Create a complementary relative link to that section in the same notebook:

[Relative link to "Navigation" section](#navigation)

Create a link to a similarly anchor named section in different notebook:

[Deeplink into another notebook](http://example.com/example.ipynb#navigation)

To reference lines of code more exactly, toggle line numbering off and on within a cell using: ESC-L

Running Multiple Code Cells

As well as running one code cell at a time, you can run multiple cells:

  • Cells -> Run All Above
  • Cells -> Run All Below
  • Cells -> Run All

Note that this will run cells taking into account the current state of the underlying kernel.

Saving, Checkpointing and Reverting the Notebook

The notebook wil autosave every few minutes.

You can also create a checkpoint using the floppy/save icon on the toolbar or File -> Save and Checkpoint.

You can revert the notebook to a saved checkpoint using File -> Revert to Saved Checkpoint.

Checking Reproducibility

One of the aims of using notebooks is to produce an executable document that can be rerun to reproduce the results.

To run cells from scratch (i.e. from a fresh kernel), Kernel -> Restart and Clear Output and then run the cells you want.

To run all the cells in the notebook from scratch: Kernel -> Restart and Run All

Troubleshooting - Permanently Running Cells

Code cells that are running (or queued for running) display an asterisk in the cell In [] indicator.

To stop execution of a running cell (and prevent queued cells from executing):

  • press the stop button on the toolbar
  • Kernel -> Interrupt

If the notebook is still hanging, you may need to restart the kernel: Kernel -> Restart

Troubleshooting - Getting Help

Code cells support autocomplete - so start typing and then tab to see what options are available...

Access documentation for a function - add a ? and run the cell: pd.DataFrame?